Inside Macintosh: Memory
Previous | Chapter Top | Chapter Contents | Next |
A relocatable block can be either locked or unlocked and either purgeable or unpurgeable. In addition, it can have its resource bit either set or cleared. To determine the state of any of these properties, use the HGetState function. To change these properties, use the HLock , HUnlock , HPurge , HNoPurge , HSetRBit , and HClrRBit procedures. To restore these properties, use the HSetState procedure.
Be sure to use these procedures to get and set the properties of relocatable blocks. In particular, do not rely on the structure of master pointers, because their structure in 24-bit mode is different from their structure in 32-bit mode.
You can use the HGetState function to get the current properties of a relocatable block (perhaps so that you can change and then later restore those properties).
FUNCTION HGetState (h: Handle): SignedByte;
The HGetState function returns a signed byte containing the flags of the master pointer for the given handle. You can save this byte, change the state of any of the flags, and then restore their original states by passing the byte to the HSetState procedure, described next.
You can use bit-manipulation functions on the returned signed byte to determine the value of a given attribute. Currently the following bits are used:
If an error occurs during an attempt to get the state flags of the specified relocatable block, HGetState returns the low-order byte of the result code as its function result. For example, if the handle h points to a master pointer whose value is NIL , then the signed byte returned by HGetState will contain the value -109.
You can use the HSetState procedure to restore properties of a block after a call to HGetState .
PROCEDURE HSetState (h: Handle; flags: SignedByte);
The HSetState procedure restores to the handle h the properties specified in the flags signed byte. See the description of the HGetState function for a list of the currently used bits in that byte. Because additional bits of the flags byte could become significant in future versions of system software, use HSetState only with a byte returned by HGetState . If you need to set two or three properties of a relocatable block at once, it is better to use the procedures that set individual properties than to manipulate the bits returned by HGetState and then call HSetState .
You can use the HLock procedure to lock a relocatable block so that it does not move in the heap. If you plan to dereference a handle and then allocate, move, or purge memory (or call a routine that does so), then you should lock the handle before using the dereferenced handle.
PROCEDURE HLock (h: Handle);
The HLock procedure locks the relocatable block to which h is a handle, preventing it from being moved within its heap zone. If the block is already locked, HLock does nothing.
If you plan to lock a relocatable block for long periods of time, you can prevent fragmentation by ensuring that the block is as low as possible in the heap zone. To do this, see the description of the ReserveMem procedure on ReserveMem .
If you plan to lock a relocatable block for short periods of time, you can prevent heap fragmentation by moving the block to the top of the heap zone before locking. For more information, see the description of the MoveHHi procedure on MoveHHi .
You can use the HUnlock procedure to unlock a relocatable block so that it is free to move in its heap zone.
PROCEDURE HUnlock (h: Handle);
The HUnlock procedure unlocks the relocatable block to which h is a handle, allowing it to be moved within its heap zone. If the block is already unlocked, HUnlock does nothing.
You can use the HPurge procedure to mark a relocatable block so that it can be purged if a memory request cannot be fulfilled after compaction.
PROCEDURE HPurge (h: Handle);
The HPurge procedure makes the relocatable block to which h is a handle purgeable. If the block is already purgeable, HPurge does nothing.
The Memory Manager might purge the block when it needs to purge the heap zone containing the block to satisfy a memory request. A direct call to the PurgeMem procedure or the MaxMem function would also purge blocks marked as purgeable.
Once you mark a relocatable block as purgeable, you should make sure that handles to the block are not empty before you access the block. If they are empty, you must reallocate space for the block and recopy the block's data from another source, such as a resource file, before using the information in the block.
If the block to which h is a handle is locked, HPurge does not unlock the block but does mark it as purgeable. If you later call HUnlock on h , the block is subject to purging.
If the Memory Manager has purged a block, you can reallocate space for it by using the ReallocateHandle procedure, described on ReallocateHandle .
You can immediately free the space taken by a handle without disposing of it by calling EmptyHandle . This procedure, described on EmptyHandle , does not require that the block be purgeable.
You can use the HNoPurge procedure to mark a relocatable block so that it cannot be purged.
PROCEDURE HNoPurge (h: Handle);
The HNoPurge procedure makes the relocatable block to which h is a handle unpurgeable. If the block is already unpurgeable, HNoPurge does nothing.
The HNoPurge procedure does not reallocate memory for a handle if it has already been purged.
If you want to reallocate memory for a relocatable block that has already been purged, you can use the ReallocateHandle procedure, described in the next section, "Managing Relocatable Blocks."